Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / boost4.arc / MANUAL.400 < prev next >

Wrap

Text File | 1988-10-23 | 52.8 KB | 1,308 lines

BOOSTERS 4.0 Tools for Turbo Pascal Programmers Users Guide Part I Copyright (C) 1988 George F. Smith & Company All Rights Reserved The Boosters library of routines and its documentation are protected by the Copyright Laws of the United States. They may not be resold, distributed, or copied without permission in writing from George F. Smith and Company. The only exception is the right of the purchaser of Boosters to make an archival copy of the distribution diskettes as a means of securing his or her investment. For information about Boosters, please contact: George F. Smith & Company 609 Candlewick Lane Lilburn, GA 30247 (404) 923-6879 Trademarks ---------- Turbo Pascal is a trademark of Borland International, Inc., Scotts Valley, CA. IBM PC, PS/2 are products of International Business Machines, Inc., Boca Raton, FL. Acknowledgements ---------------- I wish to thank Bill Meyer of Doraville, Georgia and John Jones of LaGrange Park, Illinois for their invaluable aid in getting Boosters ready for Turbo Pascal 4.0. They served as testers, advisers, and in John's case, a producer of the labels for the distribution diskettes. Boosters in General ------------------- Boosters was conceived and created to make professional or often-used programming techniques readily available whenever I needed them. It occurred to me that other programmers may find them useful, so through various channels they have made it to PCs all across North America and to more exotic places I someday hope to visit, such as Finland and Australia. Boosters supports string, video, heap, dos, and special-effects routines in TEXT mode, for any IBM PC/PS or true compatible. Many Boosters routines are coded in assembly language for speed and compactness. Nowadays, of course, windowed video interfaces are standard components of most programs, even Q&Ds. As an aid in getting (text) screens defined quickly and easily, Boosters also includes ScrGen, a screen generator. It comes with three online help panels and has been converted and upgraded for the current release. ScrGen lets you create and edit screens, while Boosters provides routines that allow programs to access the screens and use them in your programs. Boosters Version 4.0 -------------------- Boosters has been available as a support library for Turbo Pascal since November, 1985. None of the earlier releases will work correctly with Turbo Pascal 4.0 (or higher), due to fundamental changes in the operation of the compiler. The most recent release of Boosters prior to 4.0 was 2.01, which like its predecessors was a combination of inline and Pascal routines. To use a given routine from one of the older versions, it was necessary to $Include it from a disk file or copy it into the editor file. With version 4.0, programmers have in effect an extension of the Pascal language. By simply coding a "Uses Boosters;" statement at the beginning of a program, they have access to 90 functions and procedures as defined and linked by the Boosters Unit (Boosters.TPU). A simple 'Hello, world' program under version 4.0 might look like: Program World; Uses Boosters; begin PutStr (h,'Hello, World',1,1,14); end. Fortunately, most of the changes to the Boosters library in version 4.0 are internal to the routines. They do not affect the manner in which they are used in a Turbo Pascal program. There are some important distinctions and assumptions, however, that we will now discuss in detail. BOOSTERS UNIT ------------- As mentioned, the Boosters library is now a Turbo Pascal Unit, which means that the Boosters.TPU file must be accessible to your programs. You have been provided both the TPU and the PAS version of the unit on the distribution diskettes. h, v, and heap -------------- Within the interface section of the Boosters unit are type, constant, and variable definitions that in previous versions were located in file BoDecl.Pas. Version 4.0 retains the constants 'h' and 'v' for use with PutStr and GetStr, as well as names relating to heap operations, such as HeapBuf and HeapTop. However, the interface section has dropped Page : array[1..2] of HeapBuf; and replaced it with Hpage : HeapBuf; In your programs, therefore, you will have to define the heap pages you are accessing. As a suggestion, you could use: Const Npage = 5; Var Page : array[1..Npage] of HeapBuf; i : Integer; . . . BEGIN Mark (HeapTop); for i := 1 to Npage do New(Page[i]); . . . Release (HeapTop); END. { Main Program } Please notice that the variable 'i' will now be defined in your programs, as well. It is not necessary to manage the heap with Mark and Release, but it is necessary to manage the heap, so take care. Turbo Pascal v4.0 has a new compiler directive, $M, that allows you to establish stack, minimum heap, and maximum heap sizes. See page 534 of the Turbo Pascal v4.0 manual for a definition of $M. (If you use Turbo Pascal's Exec procedure, you must override the $M heapmax default to make room for the child process.) ColumnType and RowType ---------------------- Also, Boosters no longer has the ColumnType and RowType definitions. The heap and video routines that used these defintions have been redefined to accept integers as replacements. Dos Registers and Ch -------------------- Turbo Pascal comes with units of its own, most notably Crt and Dos. Both of these units are used by the Boosters unit. Within the Dos unit is a definition of the 8088's registers, called, appropriately, 'registers' (see page 299). As you will notice, Boosters.Pas uses the Dos unit's definition of this Type and calls it 'regs'--just as in previous Boosters versions. Since the Dos registers Type includes definitions for the 8- bit registers, one of which is named Ch, I decided to drop the definition of the Char type, Ch, from the Boosters unit. AnyString --------- Boosters' Type AnyString = string[255] is no longer needed since Turbo Pascal now has a Type String with the same definition. The generic string variable 's' is no longer part of Boosters. The demonstration programs use var s : string; as a general string variable. SnowRemoval and VideoSeg ------------------------ Earlier versions of Boosters had code embedded in each video routine that attempted to isolate the CGA from other video adapters so the programs could perform their functions at maximum speed without creating snow on the screen. There were several problems with this approach. One, the Boosters routines could not distinguish between a CGA and an EGA, for instance, and ended up executing snow removal code when it wasn't necessary. Two, executing snow removal routines slows video operations. So for an EGA, for instance, programmers (and users of their programs) had to pay a speed penalty. Three, Boosters gave programmers no choice about whether to remove snow or not. There are users who would gladly tolerate some snow for an increase in performance, especially since the snow effect can be neutralized somewhat through the use of colored screen backgrounds. Boosters v4.0 largely corrects this situation. It uses a boolean variable, SnowRemoval, to determine whether to execute snow removal code or not. SnowRemoval is initialized to FALSE in the initialization section of the Boosters unit. Your programs can manipulate this variable based on user input or adapter board detection code. A commercial product called Turbo Express, available at many software outlets, comes with adapter board detection algorithms, I'm told. Anyway, with SnowRemoval set to FALSE, the video routines will NOT perform snow removal, which for virtually all boards is unnecessary. Each assembler video routine used to inspect location 449h to determine whether the adapter board installed was monochrome (7) or graphics (not 7). Monochrome adapters start video memory at segment B000h, while grpahics adapters start at B800h. For version 4.0, this logic has been moved out of the assembler routines and into the initialization section of the Boosters unit. This again places control of the video segment address into the programmer's hands, while in theory picking up some speed during execution. Boosters tests LastMode, a Turbo Pascal variable, to determine whether to assign VideoSeg a value of B000h or B800h. The New and the Missing ----------------------- New routines for Boosters include the following: Dow Fil2Heap GchaHeap GetHeap GetSize Input2 PchaHeap SplitCloseH SplitCloseV SplitOpenH SplitOpenV Translate Verify WordInd In addition, several others have been modified either in name or function: ChooseOption .. Returns last key pressed Fstr .......... Argument type changed from Integer to LongInt FstrHeap ...... Now allows users to set starting x,y values for search) HeapAtt ....... Formerly HeapAt Hwipe ......... First argument is Page:HeapBuf rather than Page:Integer Input ......... Fixes a problem with moving left over blank filters ShowDate ...... Added a parameter to specify attribute ShowTime ...... Added a parameter to specify attribute Vwipe ......... First argument is Page:HeapBuf rather than Page:Integer Wait .......... Returns key pressed during pause WordN ......... Formerly Word Missing from the lineup is the Exec procedure, a version of which is now included with the Dos unit. Memory size requirements are coded with the $M directive, rather than as an argument to the procedure. Using Boosters with the heap ---------------------------- Under Boosters, the heap serves as offstage video memory. The heap routines always assume they are working with a character- attribute layout. Using the heap in this manner allows you to retain and manipulate complex or otherwise important video data without first converting it. And since data on the heap is display-ready, it can be copied to video memory instantaneously. With your data residing on the heap, there is no limit to the amount of memory available, other than physical- or operating system-imposed restrictions. As an example of using the heap with Boosters, let's assume you have an application that requires one main menu and a help screen. First, create the screens with ScrGen, saving them to a file named Sample.Gen. Save the main menu as screen 1, the help panel as screen 2. While you're in ScrGen and working with the main menu, use the ruler (Alt-U) to note the coordinates of the menu's selections. Your program to control the screens and the users' responses might look something like the following: Program Sample; Uses Crt,Boosters; Const npage = 2; { number of heap pages to allocate } F1 = #59; { F1 invokes the help screen } AltX = #45; { Alt-X ends the program } var i, ecode : Integer Page : array[1..npage] of HeapBuf; { HeapBuf is defined in Boosters.Pas } UserQuits : Boolean; c : char; BEGIN {--- Initialize variables ---} UserQuits := false; {--- Mark and allocate heap storage ---} Mark ( HeapTop ); for i := 1 to npage do new ( page[i] ); {--- Read ScrGen files into heap memory ---} { the main menu will be on page 1, } { the help panel on page 2 } Fil2Heap ( 'Sample.Gen', 1, npage, Page[1], Ecode ); {--- If an error occurred, display message and halt ---} if ecode > 0 then begin putstr ( h,'Error reading Sample.Gen',1,1,14); exit; end; {--- Display the main menu from page 1 of the heap ---} RestoreScreen ( Page[1] ); {--- Process the user's key strokes ---} repeat c := readkey; if c = #0 then begin c := readkey; case c of F1 : begin {--- display help screen ---} RestoreScreen ( Page[2] ); {--- Wait for user's keypress ---} c := readkey; if c := #0 then c := readkey; {--- Restore main menu ---} RestoreScreen ( Page[1] ); end; {--- Set flag when user presses Alt-X ---} AltX : UserQuits := true; . . {--- Process other keys ---} . end; { case } . . {--- Execute the user's menu choices ---} . until UserQuits; Release ( HeapTop ); END. { Sample program } For additional examples of using Boosters in Turbo Pascal programs, you are strongly urged to review the demonstration programs provided with the distribution diskettes. Reference Guide --------------- This section describes the routines of Boosters version 4.0. The routines are presented alphabetically. The declarations that follow assume these definitions, which are included in Boosters.Pas: Type HeapBuf = ^AnyBuf; AnyBuf = Record Screen : Array[1..4000] of Byte; End; Var HPage : HeapBuf; The heap examples assume Page to be defined as an array of HeapBuf: Const Npage = 2; { Number of heap pages } Var Page : array[1..Npage] of HeapBuf; ----------------------------------------------------------- BoDir Procedure ----------------------------------------------------------- Purpose Displays a windowed directory Declaration BoDir ( var FileSpec,FileName : String; x1,y1,x2,y2 : Integer; style, attr : byte ); Remarks Displays the directory specified in FileSpec within a box defined by (x1,y1), (x2,y2). Style and attr define the box's line-type and video attribute. The box size must have as a minimum x2 > (x1+16) and y2 > (y1+3). The directory is windowed within the box. Files are identified by color: User files - intense yellow Subdirectories - intense red Volume labels - green-blue bkgrnd Hidden files - intense yellow/blue When a box is full or the directory is exhausted, BoDir pauses and waits for one of these keypresses: Cursor key - point to next file name in current row/column. Enter - Select file and assign it to FileName Escape - Abort directory display and set FileName to null. PgDn - Display more directory entries or abort the display if none are found. FileName is set to null. Example Display the default directory. CurPath := ''; FileSpec := ''; BoDir ( FileSpec,FileName,20,5,60,12,1,14); ----------------------------------------------------------- BoErase Procedure ----------------------------------------------------------- Purpose Erases the specified file from disk. Declaration BoErase ( FileName : String; var Ecode : Integer ); Remarks Wild cards are not allowed. Ecode values: 0 - successful 2 - file not found 5 - access denied Example Erase Temp.Doc from the current directory. BoErase ('Temp.Doc',Ecode); if Ecode = 0 then PutStr (h,'File erased',1,1,14); ----------------------------------------------------------- BoRename Procedure ----------------------------------------------------------- Purpose Renames a file on the current directory. Declaration BoRename ( OldName, NewName : String; var Ecode : Integer); Remarks Take care to ensure that NewName does not already exist. Ecode values: 0 - successful 2 - OldName not found 3 - Path not found 5 - access denied Example Rename Temp.Doc to Save.Doc. BoRename ( 'Temp.Doc','Save.Doc',Ecode); if ecode = 0 then pdq ('e','File successfully renamed',1,1,14); ----------------------------------------------------------- Box Procedure ----------------------------------------------------------- Purpose Draws a box on the screen. Declaration Box ( x1,y1,x2,y2,style,att : Integer); Remarks Draws a box at (x1,y1) and (x2,y2), which specifiy the upper-right and lower-left coordinates, respectively. Box does not clear the box interior. Use Remblk or RemBlkr to clear the area inside the box. If Style > 4, then the sides of the box are drawn with chr(style). If Style is in [1..4], then Box draws a rectangle using the special box-drawing characters: Style Sides 1 single line 2 double line 3 top & bottom single, others double 4 top & bottom double, others single Att sets the video attribute of the box sides. See also BoxHeap Example Draw an 80x25 box. ClrScr; Box ( 1,1,80,25,1,14); ----------------------------------------------------------- BoxHeap Procedure ----------------------------------------------------------- Purpose Draws a box on a page of the heap. Declaration BoxHeap ( Page : Heapbuf; x1,y1,x2,y2,style,att : Integer); Remarks Draws a box at (x1,y1) and (x2,y2), which specifiy the upper-right and lower-left coordinates, respectively. BoxHeap does not clear the box interior. Use FillHeap to clear the area inside the box. If Style > 4, then the sides of the box are drawn with chr(style). If Style is in [1..4], then Box draws a rectangle using the special box-drawing characters: Style Sides 1 single line 2 double line 3 top & bottom single, others double 4 top & bottom double, others single Att sets the video attribute of the box sides. See also Box Example Draw a box on the heap and display it. ClrScr; SaveScreen ( Page[1] ); BoxHeap ( Page[1],10,5,70,15,1,14); Heap2Scr ( Page[1],10,5,70,15,10,5); ----------------------------------------------------------- Calendar Procedure ----------------------------------------------------------- Purpose Draws a calendar on the screen for the specified month and year. Declaration Calendar ( mm,year,StartCol,StartRow:Integer); Remarks The year must be 4 digits - 1966, not 66. The upper-left screen coordinates of the calendar are given by (StartCol,StartRow). The calendar is 29 columns wide and 16 rows long. See also CalHeap Example Display the calendar for December, 1982. Calendar ( 12, 1982, 25, 6 ); ----------------------------------------------------------- CalHeap Procedure ----------------------------------------------------------- Purpose Draws a calendar on a page of heap for the specified month and year. Declaration CalHeap ( Page : HeapBuf; mm,year,StartCol,StartRow:Integer); Remarks The year must be 4 digits - 1966, not 66. The upper-left screen coordinates of the calendar are given by (StartCol,StartRow). The calendar is 29 columns wide and 16 rows long. See also Calendar Example Display the calendar for August, 1981. CalHeap ( Page[1], 8, 1981, 25, 6 ); Heap2Scr ( Page[1], 25,6,53,21,1,1); ----------------------------------------------------------- CblkHeap Procedure ----------------------------------------------------------- Purpose Copies a block on a page of heap. Declaration CblkHeap ( Page : HeapBuf; x1,y1,x2,y2, x3,y3 : Integer); Remarks Copies the block on Page given by (x1,y1) and (x2,y2) to (x3,y3). See also MblkHeap Example Build and copy a box on a page of heap. BoxHeap ( Page, 25,10,40,20,1,14); CblkHeap ( Page, 25,10,40,20,9,10); ----------------------------------------------------------- Center Function ----------------------------------------------------------- Purpose Returns a string centered within a field of specified width. Declaration Center ( s : string; Width:Integer; Pad : Char); Result Type String Remarks S is centered in the result string, padded on the ends with Pad character. If S is longer than Width, only the first Width characters of S are returned. See also CtrScr Example Center 'Boosters v4.0' on line 1 of the screen. PutStr (h,Center('Boosters v4.0',80,' '), 1,1,30); ----------------------------------------------------------- ChgAtt Procedure ----------------------------------------------------------- Purpose Changes the attribute of a block in video memory. Declaration ChgAtt (x1,y1,x2,y2 : Integer; FromAtt, ToAtt : byte); Remarks Changes all FromAtt attributes to ToAtt attributes for the block defined by (x1,y1) and (x2,y2). See also SetAtt, HeapAtt Example Change red background attributes to blue. ChgAtt ( 1,1,40,15,$40,$10 ); Note that only screen positions having a red background attribute ($40) will be changed to blue ($10). All other positions will remain the same. ----------------------------------------------------------- ChooseOption Procedure ----------------------------------------------------------- Purpose Allows the user to scroll a list of choices within a menu. Declaration ChooseOption ( x1,y1,x2,y2,Nentries ; Integer; var lastkey : char ); Remarks Given a list of choices displayed within a box, ChooseOption allows the user to wrap through the choices with the up and down arrow keys. LastKey indicates whether the user canceled with Escape or selected with Enter. (x1,y1) are the coordinates of the upper-left corner of the first selection (not the box), while (x2,y2) are the lower-right coordinates of the menu box. Nentries is the number of entries in the menu. Example Allow the user to choose from a menu of 3 items. Box (20,6,60,16,1,14); RemBlk ( 21,7,59,15); CtrScr ( 'e',"Menu',39,21,7,30); pdq ('e','Breakfast',22,10,14); pdq ('e','Lunch',22,11,14); pdq ('e','Dinner',22,12,14); ChooseOption ( 22,10,60,16,3,LastKey); if LastKey = #13 then begin GetStr ( h,s,22,WhereY,10); PutStr ( h,'Meal selected is '+ strip(s,' '),1,1,14); end; ----------------------------------------------------------- CntCh Function ----------------------------------------------------------- Purpose Returns the number of occurrences of a character in a string. Declaration CntCh ( S : String; C : Char ) : Integer; Result Type Integer Remarks The search is case sensitive--'E' and 'e' are regarded as different characters. Example Count all occurrences of all letter E's, both upper- and lower-case. S := 'Easy does it'; n := CntCh ( Upper(S),'E'); ----------------------------------------------------------- Copies Function ----------------------------------------------------------- Purpose Returns N concatenated copies of character C. Declaration Copies ( C : Char; N : Integer ) : String; Result Type String See also CopyStr Example Create a string of 30 underscores. s := copies('_',30); ----------------------------------------------------------- CopyBlk Procedure ----------------------------------------------------------- Purpose Duplicates a block in video memory. Declaration CopyBlk ( x1,y1,x2,y2,x3,y3 ); Remarks Copies the block at (x1,y1) and (x2,y2) to the location beginning at (x3,y3). See also MoveBlk,CblkHeap Example Create a box and copy it to another area of the screen. Box ( 20,5,40,15,1,14 ); CopyBlk ( 20,5,40,15,50,5 ); ----------------------------------------------------------- CopyStr Function ----------------------------------------------------------- Purpose Returns N concatenated copies of string S. Declaration CopyStr ( S : String; N : Integer ) : String; Result Type String See also Copies Example Create 5 copies of 'beep-'. s := copies('beep-',5); ----------------------------------------------------------- CtrScr Procedure ----------------------------------------------------------- Purpose Center a string in video memory. Declaration CtrScr (nsew : char; s : string; length, x, y : Integer; att : byte); Remarks Centers S on the screen within a field of length 'length', which begins at (x,y). Att specifies the attribute of the centered string. NSEW determines the direction of output: N - North, bottom to top S - South, top to bottom E - East, left to right (normal) W - West, right to left CtrScr does not alter the cursor position. See also Pdq, PutStr Example Center a string at the top pf the screen. CtrScr ('e','Page 1',80,1,1,30); ----------------------------------------------------------- CursorOff Procedure ----------------------------------------------------------- Purpose Makes the cursor invisible. Declaration CursorOff; Remarks Calls Bios interrupt 10h to turn off the cursor. See also CursorOn, SetCursor Example Remove the cursor from the screen. CursorOff; ----------------------------------------------------------- CursorOn Procedure ----------------------------------------------------------- Purpose Defines a cursor of standard size. Declaration CursorOn; Remarks Calls Bios interrupt 10h to set the cursor. Uses Boosters' VideoStatus variable to determine whether monochrome or color screen. See also CursorOff, SetCursor Example Turn on the cursor. CursorOn; ----------------------------------------------------------- DiffOne Procedure ----------------------------------------------------------- Purpose Advances cursor to the first screen position different from the current one. Declaration DiffOne ( EW : Char ); Remarks Places cursor at first position that does not match the character/attribute of current cursor position. If EW is 'E' or 'e', the search is east (left-to-right). If EW is 'W' or 'w', the search is west (right-to-left). If DiffOne cannot find a non-matching position, it places the cursor at (80,25) for east searches or (1,1) for west searches. Example Advance the cursor to the next differing position. DiffOne ( 'e' ); ----------------------------------------------------------- Disk2Mem Procedure ----------------------------------------------------------- Purpose Copies a screen image from a disk file to a page of heap. Declaration Disk2Mem ( FileDesc : String; ScreenNumber : Integer; Page : HeapBuf; var Ecode : Integer ); Remarks FileDesc specifies the Drive/Path/FileName, while ScreenNumber indicates the screen number within the file to read. Screens are 4000 bytes each and are assumed to be images of video memory (character/attribute pairs). A common use of this procedure is to read files created with Boosters' ScrGen. Ecode indicates the status of the operation: 0 - Screen found and loaded onto heap 3 - Path or file not found 4 - no file handle available 5 - access denied See also Fil2Heap Example Read screen 4 of a file into page 1 of heap memory, then display it. Disk2Mem ( 'Layout.Gen',4,page[1], Ecode ); if Ecode = 0 then RestoreScreen ( Page[1] ); ----------------------------------------------------------- Dows Function ----------------------------------------------------------- Purpose Returns a day of the week string. Declaration Dows ( Month, Day, Year : Integer ) : String; Result Type String Remarks The year must be 4 digits: for example, 1955. The strings returned are: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday. They are are returned exactly as shown, first letter capitalized. See also Dow Example Find the day of the week for December 14, 1982. s := dows( 12, 14, 1982 ); pdq ('e','December 14, 1982 was a '+ s,1,1,14); ----------------------------------------------------------- Dow Function ----------------------------------------------------------- Purpose Returns a day of the week index. Declaration Dows ( Month, Day, Year : Integer ) : Integer; Result Type Integer Remarks The year must be 4 digits: for example, 1955. The values returned and their meaning are: 0 - Sunday 1 - Monday 2 - Tuesday 3 - Wednesday 4 - Thursday 5 - Friday 6 - Saturday See also Dows Example Find the day of the week for December 14, 1982. if 'Days' is defined as: const days : array[0..6] of string[2] = ('Su','Mo','Tu','We','Th','Fr','Sa'); then the function call for 12/14/1982 will be: n := dow( 12, 14, 1982 ); pdq ('e','December 14, 1982 was a '+ days[n],1,1,14); ----------------------------------------------------------------- DriveCnt Function ----------------------------------------------------------- Purpose Returns the number of logical disk drives on the host CPU. Declaration DriveCnt : Integer; Result Type Integer Remarks This function issues a call to DOS function 0Eh, which returns an initial drive count, then follows with repeated calls to DOS function 47h until the count is verified as correct. Example Display the number of drives on the system. Write('Number of drives is ',DriveCnt); ----------------------------------------------------------- Fil2Heap Procedure ----------------------------------------------------------- Purpose Copies a range of screen images into a range of heap pages. Declaration Fil2Heap ( FileDesc : String; FromScreen, ToScreen : Integer; Page : HeapBuf; var Ecode : Integer ); Remarks FileDesc specifies the Drive/Path/FileName, while FromScreen, ToScreen indicate the starting and ending screens to read into the heap beginning at Page. Screens are 4000 bytes each and are assumed to be images of video memory (character/attribute pairs). A common use of this procedure is to read files created with Boosters' ScrGen. Ecode indicates the status of the operation: 0 - Screen found and loaded onto heap 3 - Path or file not found 4 - no file handle available 5 - access denied See also Disk2Mem Example Read screens 4 through 7 into the heap beginning at Page[1]. Fil2Heap ( 'Layout.Gen',4,7,page[1], Ecode ); if Ecode = 0 then RestoreScreen ( Page[1] ); ----------------------------------------------------------- FileStamp Procedure ----------------------------------------------------------- Purpose Gets or sets a file's time/date stamp. Declaration FileStamp ( FileName : String; GetSet : Integer; Var Ecode : Integer ); Remarks Attempts to open FileName, read or write the time/date stamp, and close the file. GetSet = 0 for reading, GetSet = 1 for writing time/date. Uses global variables: FileHH, FileMin, FileSec (time) FileYY, FileMM, FileDD (date) FileYY must be 4 digits - e.g., 1988. FileHH (hour) is in military format - e.g., 2:00 p.m. is 14. Ecode = 0 if the operation was successful, or a DOS error code if unsuccessful. See also GetFtime (in Turbo Pascal DOS unit) Example Read the file stamp for Boosters.Pas. FileStamp ( 'Boosters.Pas',0,Ecode ); if Ecode = 0 then begin WriteLn(FileHH,':',FileMin,':',FileSec); WriteLn(FileMM,'/',FileDD, '/',FileYY-1900); end; ----------------------------------------------------------- FillHeap Procedure ----------------------------------------------------------- Purpose Initializes a block of heap. Declaration FillHeap ( Page : HeapBuf; x1,y1,x2,y2 : Integer; C : Char; Att : Byte ); Remarks The block defined by (x1,y1) and (x2,y2) is set to values specified by C and Att. Example Clear a page of heap without disturbing the screen. FillHeap ( 1,1,80,25,#32,7 ); ----------------------------------------------------------- FindStr Procedure ----------------------------------------------------------- Purpose Searches video memory for string S, positioning the cursor at a specified point relative to S. Declaration FindStr ( x,y : Integer; s : string; offset : Integer; var ecode : Integer ); Remarks Beginning at (x,y), FindStr searches for S. If S is found, FindStr sets Ecode = 0 and places the cursor according to the value of OffSet: OffSet Cursor Placement =0 S[1] <0 S[1]-OffSet >0 S[1]+OffSet If FindStr can't find S, it sets Ecode = 1 and puts the cursor at (80,25). See also FstrHeap Example Search for 'log' and highlight the 'g' if found. FindStr ( 1,1,'log',2,ecode); if ecode = 0 then SetAtt (Wherex,WhereY,WhereX,WhereY,112); ----------------------------------------------------------- Fstr Function ----------------------------------------------------------- Purpose Converts a LongInt to a string. Declaration Fstr (num:LongInt; width:Integer) : String; Result Type String Remarks Num is converted to a string, right-justified in a field of Width characters. This is Turbo's Str procedure made available as a function for convenience. Example Display Integer 15 using Pdq. n := 15; Pdq('e',Fstr(n,3),15,5,14); ----------------------------------------------------------- FstrHeap Procedure ----------------------------------------------------------- Purpose Searches a page of heap for string S. Declaration FstrHeap ( Hpage:HeapBuf; S:String; var x,y,ecode : Integer); Remarks Beginning at (x,y) on Page, FstrHeap searches for S. If S is found, FstrHeap sets Ecode = 0 and returns the coordinates of S[1] in (x,y). FstrHeap sets Ecode = 1 if it cannot find S on Page. See also FindStr Example Find 'log' on page 1 of the heap and load it into S. x := 1; y := 1; FstrHeap ( Page[1],'log',x,y,ecode ); if ecode = 0 then GetHeap ( Page[1],h,s,x,y,3); ----------------------------------------------------------- GchaHeap Function ----------------------------------------------------------- Purpose Gets a character/attribute word from the heap. Declaration GchaHeap ( Hpage:HeapBuf; x,y:Integer ) :Integer; Result Type Integer Remarks Returns the character/attribute pair located at (x,y) on Page. See also PchaHeap Example Get the character/attribute combination at 1,1 on page 2 of the heap. n := GchaHeap ( Page[2],1,1); ----------------------------------------------------------- GetAtt Function ----------------------------------------------------------- Purpose Gets the video attribute at (x,y). Declaration GetAtt ( x,y:Integer ) : byte; Result Type Byte Remarks Returns the attribute found at (x,y) of video memory. See also GetChar, HeapAtt. Example Get the attribute associated with the first character of the string, 'Menu', in video memory. FindStr ( 1,1,'Menu',0,ecode); if ecode = 0 then n := GetAtt ( WhereX,WhereY ); ----------------------------------------------------------- GetChar Function ----------------------------------------------------------- Purpose Gets the character at (x,y) on the screen. Declaration GetChar ( x,y:Integer ) : Char; Result Type Char Remarks Returns the character found at (x,y) of video memory. See also GetAtt. Example Get the character following the colon on line 3 of the screen. FindStr ( 1,3,':',1,ecode); if ecode = 0 then c := GetChar ( WhereX,WhereY ); ----------------------------------------------------------- GetHeap Procedure ----------------------------------------------------------- Purpose Reads a string from a page of heap. Declaration GetHeap ( Hpage:HeapBuf; hv:Char; S:String; x,y,len : Integer ); Remarks Reads Len characters into S beginning at (x,y) of Page. If HV = 'V' or 'v', then the read direction is vertical or top-to- bottom. If HV is any other character, the read direction will be horizontal or left- to-right. See also GetStr Example Read 'October' from 15,5 of Page 1. GetHeap ( Page[1],h,15,5,7 ); ----------------------------------------------------------- GetSize Procedure ----------------------------------------------------------- Purpose Returns the size of a disk file. Declaration GetSize ( FileDesc:String; var Size:LongInt; var Ecode:Integer ); Remarks Returns the number of bytes in the drive/path/ file specified by FileDesc. If Ecode = 0, the file was found and Size = filesize. If Ecode <> 0, then a problem occurred and Size is unchanged. Example Get the size of a file in bytes. GetSize ( '\pascal\tp.exe',size,ecode ); if ecode = 0 then write('Tp.Exe is ',size div 1024,'K'); ----------------------------------------------------------- GetStr Procedure ----------------------------------------------------------- Purpose Reads a string from the screen. Declaration GetStr ( hv:Char; S:String; X,Y:Integer; Len:Byte ); Remarks Reads Len characters into S beginning at (x,y) on the screen. If HV = 'V' or 'v' then the read direction is vertical or top-to- bottom. If HV is any other character, then the read direction is horizontal or left-to- right. See also GetHeap Example Read the date from the screen. Assuming the string '12/25/89' begins at 1,25 on the screen, then GetStr ( h,Today,1,25,8 ); will store it in the string 'Today'. ----------------------------------------------------------- Heap2Scr Procedure ----------------------------------------------------------- Purpose Copies a block of heap to the screen. Declaration Heap2Scr ( Hpage:HeapBuf; x1,y1,x2,y2,x3,y3: Integer ); Remarks Copies the block on Page defined by (x1,y1) and (x2,y2) to the screen beginning at (x3,y3). See also RestoreScreen,Scr2Heap Example Display a menu on the current screen. {--- Save the current screen ---} SaveScreen ( Page[1] ); {--- Copy the menu to (60,1) of the Screen ---} Heap2Scr ( Page[2],1,1,15,10,60,1 ); {--- Wait for a keypress ---} c := readkey; if c = #0 then c := readkey; . . {--- Erase the menu ---} RestoreScreen ( Page[1] ); ----------------------------------------------------------- HeapAtt Procedure ----------------------------------------------------------- Purpose Sets the video attributes of a screen image stored on the heap. Declaration HeapAtt ( Hpage:HeapBuf; x1,y1,x2,y2:Integer; Att:Byte ); Remarks Sets all locations to attribute Att for the block defined by (x1,y1) and (x2,y2) on Page. See also SetAtt Example Set the attributes of Page[1] to reverse video. HeapAtt ( Page[1],1,1,80,25,112 ); ----------------------------------------------------------- Hex Function ----------------------------------------------------------- Purpose Converts an integer to a hexadecimal string. Declaration Hex ( DecimalValue : Word ) : String; Result Type String Remarks The four nibbles of DecimalValue are expressed as a hexadecimal constant in ascii. Example Express 16384 as a hex string. write( Hex(16384) ); { will display 4000 } ----------------------------------------------------------- Hwipe Procedure ----------------------------------------------------------- Purpose Horizontally wipes a block from the heap to the screen. Declaration Hwipe ( Hpage:HeapBuf; x1,y1,x2,y2,x3,y3, delay : Integer ); Remarks Creates a horizontal wipe effect by writing a block from the heap to the screen one column at a time. Delay controls the speed of the wipe. Hwipe takes the block at (x1,y1) and (x2,y2) and writes it to (x3,y3) of the screen. See also Vwipe, Tile, SplitOpenH, SplitCloseH, SplitOpenV, SplitCloseV Example Wipe Page[1] to the screen. Hwipe ( Page[1], 1,1,80,25,1,1,5 ); ----------------------------------------------------------- Input Procedure ----------------------------------------------------------- Purpose Gets filtered data from the keyboard (Stdin). Declaration Input ( x,y : Integer; Filter : String; var Data : String; var LastCh : Char; Att : Byte ); Remarks Positions the cursor at (x,y) and waits for a keypress. The contents of Filter determine which characters are accepted and placed in Data. Input is terminated when an Esc, CR, Tab, Reverse Tab, or EOF is received. The terminating character is placed in LastCh. Att is the attribute of the input characters as they appear on the screen. Input initializes Data to a string of blanks equal in length to Filter. If the procedure is terminated with an Esc, Data is returned as a null string. Otherwise, Data is returned with the accepted keypresses and the blanks. Filter Values Allowable keystrokes or program response C Any character D 0..9 I 0..9 space R 0..9 . space S + - space space Input denied at this position; cursor advanced right 1 position All others Keystroke must match Filter value. Tab and Reverse Tab are used as terminators to allow users to key data into multiple input fields by tabbing between them. Input accepts left and right cursor arrows to move the cursor. When an end of field is reached, Input wraps to the other end. See also Input2 Example Accept the user's social security number. {--- Define acceptable keystrokes ---} Filter := 'DDD DD DDDD'; {--- Display the message and field format ---} Message := 'Enter your SSN: '; Len := Length(Message); PutStr (h,Message,10,8,14 ); PutStr (h,'- -',Len+13,8,14); {--- Get user's SSN ---} Input ( Len+10,8,Filter,Data,LastKey,14 ); if LastKey <> #27 then begin Data := strip(Data); Data := translate(Data,'-',' ',' '); end; ----------------------------------------------------------- Input2 Procedure ----------------------------------------------------------- Purpose Gets filtered data from the keyboard (Stdin). Declaration Input2 ( x,y : Integer; Filter : String; var Data : String; var LastCh : Char; Att : Byte ); Remarks Positions the cursor at (x,y) and waits for a keypress. Differs from Input Procedure by allowing Function keys F1-F10 to terminate processing. ----------------------------------------------------------- LastPos Function ----------------------------------------------------------- Purpose Returns the starting position of Needle in HayStack by searching backwards. Declaration LastPos ( Needle, HayStack : String; Start : Integer ) : Integer; Result Type Integer; Remarks Begins at Start and proceeds towards the beginning of HayStack until Needle is found or HayStack is exhausted. If Needle is found, LastPos returns its starting position in HayStack. LastPos returns zero when: - Needle is not found - Needle is longer than HayStack - Start is less than 1 or greater than the length of HayStack - Needle is null - HayStack is null See also PosR, Pos (Turbo Pascal) Example Find the position of the last 's' in 'Boosters'. LastS := LastPos ( 's','Boosters', 8); {--- LastS will equal 8 ---} ----------------------------------------------------------- Left Function ----------------------------------------------------------- Purpose Left-justifies and pads a string in a field. Declaration Left ( S : String; Width : Integer; Pad : Char ) : String; Result Type String Remarks Returns S left-justified and padded on the right with Pad characters, if necessary, in a field of size Width. See also Right, Center Example Left-justify 'Name' for data entry. Field1 := Left('Name ',35,'_'); ----------------------------------------------------------- Lower Function ----------------------------------------------------------- Purpose Converts uppercase characters to lowercase. Declaration Lower ( S : String ) : String; Result Type String Remarks Returns a string with all uppercase characters of S converted to lowercase. See also Upper Example Ensure that a string is all lowercase. S := Lower( S );